<!DOCTYPE HTML>
<html>
<head>
<title>IPv6 plugin API</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
<h1>IPv6 plugin API</h1>
<p>
<strong>Note:</strong> The IPv6 plugin hasn't been tested.  Your help in testing it is appreciated.
</p>
<p>
The IPv6 plugin measures various IPv6 related metrics.  It is encapsulated within
the <code>BOOMR.plugins.IPv6</code> namespace.  This plugin tries to do a few things:
</p>
<ul>
<li>Check if the client can connect to an ipv6 address</li>
<li>Check if the client can resolve DNS that points to an ipv6 address</li>
<li>Check latency of connecting to an ipv6 address</li>
<li>Check avg latency of doing dns lookup to an ipv6 address (not worstcase)</li>
</ul>
<p>
This plugin needs a server that has an IPv6 address, and a DNS name to point to it.
Additionally, the server needs to be configured to serve content requested
from the IPv6 address and should not require a virtual host name.  This means
that you probably cannot use shared hosting that puts multiple hosts on the
same IP address.
</p>

<h2 id="config">Configuration</h2>
<p>
All configuration parameters are within the IPv6 namespace.
</p>
<dl>
<dt>ipv6_url</dt>
<dd>An image URL referenced by its IPv6 address, eg, <code>http://fe80::1/image-i.png</code>.
If not specified, the test will abort.</dd>
<dt>host_url</dt>
<dd><strong>[recommended]</strong>
An image URL on an IPv6 only host referenced by its DNS hostname. The hostname should not
resolve to an IPv4 address.  If not specified, the host test will be skipped.
</dd>
<dt>timeout</dt>
<dd><strong>[optional]</strong>
The time, in milliseconds, that boomerang should wait for a network response before giving up
and assuming that the request failed.  The default is 1200ms.
</dd>
</dl>

<h2 id="methods">Methods</h2>

<dl class="api">

<dt>init(oConfig)</dt>
<dd>
<p>
Called by the <a href="BOOMR.html#init">BOOMR.init()</a> method to configure the DNS
plugin.  See the <a href="#config">Configuration section</a> for details.
</p>
<pre>
BOOMR.init({
		<em>IPv6: {                                                         </em>
		<em>            ipv6_url: "http://fe80::1/images/image-i.png"       </em>
		<em>            host_url: "http://yoursite-6.com/images/image-i.png"</em>
		<em>}                                                               </em>
	});
</pre>

<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.IPv6</code> object, so you can chain methods.
</p>
<h3>Note</h3>
<p>
The IPv6 test will not run if a <code>ipv6_url</code> is not configured.
</p>
</dd>

<dt>is_complete()</dt>
<dd>
<p>
Called by <a href="BOOMR.html#sendBeacon">BOOMR.sendBeacon()</a> to determine if the IPv6 plugin has
finished what it's doing or not.
</p>
<h3>Returns</h3>
<ul>
<li><code>true</code> if the plugin has completed.</li>
<li><code>false</code> if the plugin has not completed.</li>
</ul>
</dd>

</dl>

<h2 id="beacon">Beacon Parameters</h2>
<p>
This plugin adds two parameters to the beacon, both prefixed with <code>ipv6_</code>:
</p>
<dl>
<dt>ipv6_latency</dt>
<dd>Latency in milliseconds of getting data from an ipv6 host when connecting to the IP.
Will be set to NA if the client cannot connect to the ipv6 host.</dd>
<dt>ipv6_lookup<dt>
<dd>Latency of getting data from a hostname that resolves to an ipv6 address.  Will be set
to NA if the client cannot resolve or connect to the ipv6 host.</dd>
</dl>

<p class="perma-link">
The latest code and docs is available on <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a>
</p>

</body>
</html>
<!--
    Copyright (c) 2011, Yahoo! Inc.  All rights reserved.
    Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms.
-->
